*************************************************************************
 ATARI Radeon XBIOS VIDIX functions
*************************************************************************
XBIOS Functions list:

vdxGetVersion()          XBIOS function 400 - mandatory
vdxProbe()               XBIOS function 401 - mandatory
vdxInit()                XBIOS function 402 - optional
vdxDestroy()             XBIOS function 403 - optional
vdxGetCapability()       XBIOS function 404 - mandatory
vdxQueryFourcc()         XBIOS function 405 - mandatory
vdxConfigPlayback()      XBIOS function 406 - mandatory
vdxPlaybackOn()          XBIOS function 407 - mandatory
vdxPlaybackOff()         XBIOS function 408 - mandatory
vdxPlaybackFrameSelect() XBIOS function 409 - optional
vdxGetGrKeys()           XBIOS function 410 - optional
vdxSetGrKeys()           XBIOS function 411 - optional
vdxPlaybackGetEq()       XBIOS function 412 - optional
vdxPlaybackSetEq()       XBIOS function 413 - optional
vdxPlaybackGetDeint()    XBIOS function 414 - optional
vdxPlaybackSetDeint()    XBIOS function 415 - optional
vdxPlaybackCopyFrame()   XBIOS function 416 - optional
vdxQueryDMAStatus()      XBIOS function 417 - optional


*************************************************************************
			vdxGetVersion    
*************************************************************************

  Opcode:
       XBIOS 400

  Syntax:
       unsigned vdxGetVersion(void);

  Description:
          Get the version.

  Binding:
          move.w  #400,-(sp)
          trap    #14
          addq.l  #2,sp
          
  Return: Version.

*************************************************************************
			vdxProbe    
*************************************************************************

  Opcode:
       XBIOS 401

  Syntax:
       int vdxProbe(int verbose,int force);

  Description:
          Probe the board.
          Verbose and force are unused for the Atari driver.

  Binding:
          move.l  force,-(sp)
          move.l  verbose,-(sp)
          move.w  #401,-(sp)
          trap    #14
          lea.l   10(sp),sp
          
  Return: Driver should return 0 if it can handle something else 
          ENXIO.
          
*************************************************************************
			vdxInit    
*************************************************************************

  Opcode:
       XBIOS 402

  Syntax:
       int vdxInit(void);

  Description:
          Initialize the VIDIX driver.

  Binding:
          move.w  #402,-(sp)
          trap    #14
          addq.l  #2,sp
          
  Return: Driver should return 0.

*************************************************************************
			vdxDestroy    
*************************************************************************

  Opcode:
       XBIOS 403

  Syntax:
       void vdxDestroy(void);

  Description:
          Quit the VIDIX driver.

  Binding:
          move.w  #403,-(sp)
          trap    #14
          addq.l  #2,sp
          
  Return: Nothing.

*************************************************************************
			vdxGetCapability    
*************************************************************************

  Opcode:
       XBIOS 404

  Syntax:
       int vdxGetCapability(vidix_capability_t *to);

  Description:
          Driver should return capability with filled vidix_capability_t.type field.

  to structure:
       typedef struct vidix_capability_s
       {
           char    name[64];    /* Driver name */
           char    author[64];  /* Author name */
       #define TYPE_OUTPUT      0x00000000    /* Is a video playback device */
       #define TYPE_CAPTURE     0x00000001    /* Is a capture device */
       #define TYPE_CODEC       0x00000002    /* Device supports hw (de)coding */
       #define TYPE_FX          0x00000004    /* Is a video effects device */
           int    type;         /* Device type, see below */
           unsigned reserved0[4];
           int    maxwidth;
           int    maxheight;
           int    minwidth;
           int    minheight;
           int    maxframerate; /* -1 if unlimited */
       #define FLAG_NONE        0x00000000 /* No flags defined */
       #define FLAG_DMA         0x00000001 /* Card can use DMA */
       #define FLAG_EQ_DMA      0x00000002 /* Card can use DMA only if src pitch == dest pitch */
       #define FLAG_UPSCALER    0x00000010 /* Card supports hw upscaling */
       #define FLAG_DOWNSCALER  0x00000020 /* Card supports hw downscaling */
       #define FLAG_SUBPIC      0x00001000 /* Card supports DVD subpictures */
       #define FLAG_EQUALIZER   0x00002000 /* Card supports equalizer */
           unsigned flags;      /* Feature flags, see above */
           unsigned short vendor_id;
           unsigned short device_id;
           unsigned reserved1[4];
       }vidix_capability_t;

  Binding:
          pea.l   to
          move.w  #404,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.

*************************************************************************
			vdxQueryFourcc    
*************************************************************************

  Opcode:
       XBIOS 405

  Syntax:
       int vdxQueryFourcc(vidix_fourcc_t *to);

  Description:
          Select requested fourcc, witdh and height
          Driver should answer - can it configure video memory for given fourcc or not.

  to structure:
       typedef struct vidix_fourcc_s
       {
           unsigned fourcc; /* input: requested fourcc */
           unsigned srcw;   /* input: hint: width of source */
           unsigned srch;   /* input: hint: height of source */
       #define VID_DEPTH_NONE             0x0000
       #define VID_DEPTH_1BPP             0x0001
       #define VID_DEPTH_2BPP             0x0002
       #define VID_DEPTH_4BPP             0x0004
       #define VID_DEPTH_8BPP             0x0008
       #define VID_DEPTH_12BPP            0x0010
       #define VID_DEPTH_15BPP            0x0020
       #define VID_DEPTH_16BPP            0x0040
       #define VID_DEPTH_24BPP            0x0080
       #define VID_DEPTH_32BPP            0x0100
           unsigned depth; /* output: screen depth for given fourcc */
       #define VID_CAP_NONE               0x0000
       #define VID_CAP_EXPAND             0x0001 /* if overlay can be bigger than source */
       #define VID_CAP_SHRINK             0x0002 /* if overlay can be smaller than source */
       #define VID_CAP_BLEND              0x0004 /* if overlay can be blended with framebuffer */
       #define VID_CAP_COLORKEY           0x0008 /* if overlay can be restricted to a colorkey */
       #define VID_CAP_ALPHAKEY           0x0010 /* if overlay can be restricted to an alpha channel */
       #define VID_CAP_COLORKEY_ISRANGE   0x0020 /* if the colorkey can be a range */
       #define VID_CAP_ALPHAKEY_ISRANGE   0x0040 /* if the alphakey can be a range */
       #define VID_CAP_COLORKEY_ISMAIN    0x0080 /* colorkey is checked against framebuffer */
       #define VID_CAP_COLORKEY_ISOVERLAY 0x0100 /* colorkey is checked against overlay */
       #define VID_CAP_ALPHAKEY_ISMAIN    0x0200 /* alphakey is checked against framebuffer */
       #define VID_CAP_ALPHAKEY_ISOVERLAY 0x0400 /* alphakey is checked against overlay */
           unsigned flags; /* output: capability */
       }vidix_fourcc_t;

  Binding:
          pea.l   to
          move.w  #405,-(sp)
          trap    #14
          adq.l   #6,sp
          
  Return: Driver should return 0 else ENOSYS.
          
*************************************************************************
			vdxConfigPlayback    
*************************************************************************

  Opcode:
       XBIOS 406

  Syntax:
       int vdxConfigPlayback(vidix_playback_t *info);

  Description:
          Driver should prepare BES on this call.

          APP pass to driver following info:
          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
          vidix_playback_t.fourcc       - contains fourcc of movie
          vidix_playback_t.capability   - currently contsinas copy of vidix_capability_t.flags
          vidix_playback_t.blend_factor - currently unused   
          vidix_playback_t.src          - x,y,w,h fields contain original movie size
                                          (in pixels) x and y often are nulls.
          vidix_playback_t.src.pitch.y    These fields contain source pitches
          vidix_playback_t.src.pitch.u  - for each Y,U,V plane in bytes.
          vidix_playback_t.src.pitch.v    (For packed fourcc only Y value is used)
                                          They are hints for driver to use same destinition
                                          pitches as in source memory (to speed up
                                          memcpy process).
                                          Note: when source pitches are unknown or
                                          variable these field will be filled into 0.
          vidix_playback_t.dest	- x,y,w,h fields contains destinition rectange
                                  on the screen in pixels.
          vidix_playback_t.num_frames - maximal # of frames which can be used by APP.
                                        (Currently 10).
          Driver should fill following fields:
          ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
          vidix_playback_t.num_frames   - real # of frames which will be used by driver.
                                          (Should be less or equal to app's num_frames).			  
          vidix_playback_t.dest.pitch.y   These fields should contain alignment
          vidix_playback_t.dest.pitch.u - for each Y,U,V plane in bytes.
          vidix_playback_t.dest.pitch.v   (For packed fourcc only Y value is used)  
          vidix_playback_t.frame_size   - Driver should tell to app which size of
                                          source frame (src.w and src.h) should
                                          use APP (according to pitches and offsets)
          vidix_playback_t.offsets      - offsets from begin of BES memory for each frame  
          vidix_playback_t.offset.y       These field should contain offset
          vidix_playback_t.offset.u     - for each Y,U,V plane within frame.
          vidix_playback_t.offset.v       (For packed fourcc only Y value is used)
          vidix_playback_t.dga_addr     - Address of BES memory.
   
          Also see this picture:

          VIDEO MEMORY layout:
           +-----------  It's begin of video memory     End of video memory--------------+
           |                                                                             |
           v                                                                             v
           [      RGB memory                         |         YUV memory    |  UNDEF    ]
                                                     ^
                                                     |
                                                     +---- begin of BES memory         
          BES MEMORY layout:
           +-------- begin of BES memory
           |
           v
           [ | |                      |       |       |
             ^ ^                      ^       ^       ^
             | |                      |       |       + BEGIN of second frame
             | |                      |       + BEGIN of V plane
             | |                      + BEGIN of U plane
             | +------- BEGIN of Y plane
             |
             +--------- BEGIN of first frame
          
          This means that in general case:
          offset of frame != offset of BES
          offset of Y plane != offset of first frame

          But often: vidix_playback_t.offsets[0] = vidix_playback_t.offset.y = 0;

          Formula: (For Y plane) copy source to:
                   vidix_playback_t.dga_addr + vidix_playback_t.offsets[i] + vidix_playback_t.offset.y

  info structure:
       typedef struct vidix_playback_s
       {
           unsigned fourcc;        /* app -> driver: movies's fourcc */
           unsigned capability;    /* app -> driver: what capability to use */
           unsigned blend_factor;  /* app -> driver: blending factor */
           vidix_rect_t src;       /* app -> driver: original movie size */
           vidix_rect_t dest;      /* app -> driver: destinition movie size. driver->app dest_pitch */
       #define VID_PLAY_INTERLEAVED_UV 0x00000001    /* driver -> app: interleaved UV planes */
       #define INTERLEAVING_UV         0x00001000    /* UVUVUVUVUV used by Matrox G200 */
       #define INTERLEAVING_VU         0x00001001    /* VUVUVUVUVU */
           int        flags;
           /* memory model */
           unsigned frame_size;    /* driver -> app: destinition frame size */
           unsigned num_frames;    /* app -> driver: after call: driver -> app */
       #define VID_PLAY_MAXFRAMES 64   /* reasonable limitation for decoding ahead */
           unsigned offsets[VID_PLAY_MAXFRAMES];    /* driver -> app */
           vidix_yuv_t    offset;  /* driver -> app: relative offsets within frame for yuv planes */
           void *dga_addr;         /* driver -> app: linear address */
       }vidix_playback_t;

  Binding:
          pea.l   info
          move.w  #406,-(sp)
          trap    #14
          adq.l   #6,sp
          
  Return: Driver should return 0.
 
*************************************************************************
			vdxPlaybackOn    
*************************************************************************

  Opcode:
       XBIOS 407

  Syntax:
       int vdxPlaybackOn(void);

  Description:
          Driver should activate BES on this call.

  Binding:
          move.w  #407,-(sp)
          trap    #14
          addq.l  #2,sp
          
  Return: Driver should return 0.
          
*************************************************************************
			vdxPlaybackOff    
*************************************************************************

  Opcode:
       XBIOS 408

  Syntax:
       int vdxPlaybackOff(void);

  Description:
          Driver should deactivate BES on this call.

  Binding:
          move.w  #408,-(sp)
          trap    #14
          addq.l  #2,sp
          
  Return: Driver should return 0.
          
*************************************************************************
			vdxPlaybackFrameSelect    
*************************************************************************

  Opcode:
       XBIOS 409

  Syntax:
       int vdxPlaybackFrameSelect(unsigned frame);

  Description:
          Driver should prepare and activate corresponded frame.
          This function is used only for double and trilpe buffering and
          never used for single buffering playback.

  Binding:
          move.l  frame,-(sp)
          move.w  #409,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.

*************************************************************************
			vdxGetGrKeys    
*************************************************************************

  Opcode:
       XBIOS 410

  Syntax:
       int vdxGetGrKeys(vidix_grkey_t *grkey);

  Description:
          This interface should be tuned but introduced for overlapped playback
          and video effects (TYPE_FX)

  grkey structure:
       typedef struct vidix_grkey_s
       {
           vidix_ckey_t    ckey;      /* driver -> app: color key */
           vidix_vkey_t    vkey;      /* driver -> app: video key */
       #define KEYS_PUT    0
       #define KEYS_AND    1
       #define KEYS_OR     2
       #define KEYS_XOR    3
           unsigned    key_op;        /* driver -> app: keys operations */
       }vidix_grkey_t;

  Binding:
          pea.l   grkey
          move.w  #410,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.
  
*************************************************************************
			vdxSetGrKeys    
*************************************************************************

  Opcode:
       XBIOS 411

  Syntax:
       int vdxSetGrKeys(const vidix_grkey_t *grkey);

  Description:
          This interface should be tuned but introduced for overlapped playback
          and video effects (TYPE_FX).

  grkey structure:
       typedef struct vidix_grkey_s
       {
           vidix_ckey_t    ckey;      /* app -> driver: color key */
           vidix_vkey_t    vkey;      /* app -> driver: video key */
       #define KEYS_PUT    0
       #define KEYS_AND    1
       #define KEYS_OR     2
       #define KEYS_XOR    3
           unsigned    key_op;        /* app -> driver: keys operations */
       }vidix_grkey_t;

  Binding:
          pea.l   grkey
          move.w  #411,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.
  
*************************************************************************
			vdxPlaybackGetEq    
*************************************************************************

  Opcode:
       XBIOS 412

  Syntax:
       int vdxPlaybackGetEq(vidix_video_eq_t * eq);

  Description:
          Function for get color correction.

  eq structure:
       typedef struct vidix_video_eq_s
       {
       #define VEQ_CAP_NONE            0x00000000UL
       #define VEQ_CAP_BRIGHTNESS      0x00000001UL
       #define VEQ_CAP_CONTRAST        0x00000002UL
       #define VEQ_CAP_SATURATION      0x00000004UL
       #define VEQ_CAP_HUE             0x00000008UL
       #define VEQ_CAP_RGB_INTENSITY   0x00000010UL
           int        cap;             /* should contain capability of equalizer */
       /* end-user app can have presets like: cold-normal-hot picture and so on */
           int        brightness;      /* -1000 : +1000 */
           int        contrast;        /* -1000 : +1000 */
           int        saturation;      /* -1000 : +1000 */
           int        hue;             /* -1000 : +1000 */
           int        red_intensity;   /* -1000 : +1000 */
           int        green_intensity; /* -1000 : +1000 */
           int        blue_intensity;  /* -1000 : +1000 */
       #define VEQ_FLG_ITU_R_BT_601    0x00000000 /* ITU-R BT.601 colour space (default) */
       #define VEQ_FLG_ITU_R_BT_709    0x00000001 /* ITU-R BT.709 colour space */
       #define VEQ_FLG_ITU_MASK        0x0000000f
           int        flags;           /* currently specifies ITU YCrCb color space to use */
       }vidix_video_eq_t;

  Binding:
          pea.l   eq
          move.w  #412,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.
  
*************************************************************************
			vdxPlaybackSetEq    
*************************************************************************

  Opcode:
       XBIOS 413

  Syntax:
       int vdxPlaybackSetEq(const vidix_video_eq_t * eq;

  Description:
          Function for set color correction.

  eq structure:
       typedef struct vidix_video_eq_s
       {
       #define VEQ_CAP_NONE            0x00000000UL
       #define VEQ_CAP_BRIGHTNESS      0x00000001UL
       #define VEQ_CAP_CONTRAST        0x00000002UL
       #define VEQ_CAP_SATURATION      0x00000004UL
       #define VEQ_CAP_HUE             0x00000008UL
       #define VEQ_CAP_RGB_INTENSITY   0x00000010UL
           int        cap;             /* should contain using fields */
       /* end-user app can have presets like: cold-normal-hot picture and so on */
           int        brightness;      /* -1000 : +1000 */
           int        contrast;        /* -1000 : +1000 */
           int        saturation;      /* -1000 : +1000 */
           int        hue;             /* -1000 : +1000 */
           int        red_intensity;   /* -1000 : +1000 */
           int        green_intensity; /* -1000 : +1000 */
           int        blue_intensity;  /* -1000 : +1000 */
       #define VEQ_FLG_ITU_R_BT_601    0x00000000 /* ITU-R BT.601 colour space (default) */
       #define VEQ_FLG_ITU_R_BT_709    0x00000001 /* ITU-R BT.709 colour space */
       #define VEQ_FLG_ITU_MASK        0x0000000f
           int        flags;           /* currently specifies ITU YCrCb color space to use */
       }vidix_video_eq_t;

  Binding:
          pea.l   eq
          move.w  #413,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.

*************************************************************************
			vdxPlaybackGetDeint    
*************************************************************************

  Opcode:
       XBIOS 414

  Syntax:
       int vdxPlaybackGetDeint(vidix_deinterlace_t * info);

  Description:
          Function for get interlacing.

  info structure:
       typedef struct vidix_deinterlace_s
       {
       #define CFG_NON_INTERLACED        0x00000000 /* stream is not interlaced */
       #define CFG_INTERLACED            0x00000001 /* stream is interlaced */
       #define CFG_EVEN_ODD_INTERLACING  0x00000002 /* first frame contains even fields but second - odd */
       #define CFG_ODD_EVEN_INTERLACING  0x00000004 /* first frame contains odd fields but second - even */
       #define CFG_UNIQUE_INTERLACING    0x00000008 /* field deinterlace_pattern is valid */
       #define CFG_UNKNOWN_INTERLACING   0x0000000f /* unknown deinterlacing - use adaptive if it's possible */
           unsigned    flags;               /* driver -> app */
           unsigned    deinterlace_pattern; /* driver -> app: deinterlace pattern if flag CFG_UNIQUE_INTERLACING is set */
       }vidix_deinterlace_t;

  Binding:
          pea.l   info
          move.w  #414,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.

*************************************************************************
			vdxPlaybackSetDeint    
*************************************************************************

  Opcode:
       XBIOS 415

  Syntax:
       int vdxPlaybackSetDeint(vidix_deinterlace_t * info);

  Description:
          Function for set interlacing.

  info structure:
       typedef struct vidix_deinterlace_s
       {
       #define CFG_NON_INTERLACED        0x00000000 /* stream is not interlaced */
       #define CFG_INTERLACED            0x00000001 /* stream is interlaced */
       #define CFG_EVEN_ODD_INTERLACING  0x00000002 /* first frame contains even fields but second - odd */
       #define CFG_ODD_EVEN_INTERLACING  0x00000004 /* first frame contains odd fields but second - even */
       #define CFG_UNIQUE_INTERLACING    0x00000008 /* field deinterlace_pattern is valid */
       #define CFG_UNKNOWN_INTERLACING   0x0000000f /* unknown deinterlacing - use adaptive if it's possible */
           unsigned    flags;
           unsigned    deinterlace_pattern; /* app -> driver: deinterlace pattern if flag CFG_UNIQUE_INTERLACING is set */
       }vidix_deinterlace_t;

  Binding:
          pea.l   info
          move.w  #415,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0.

*************************************************************************
			vdxPlaybackCopyFrame    
*************************************************************************

  Opcode:
       XBIOS 416

  Syntax:
       int vdxPlaybackCopyFrame(vidix_dma_t *dmai);

  Description:
          Function for copy frame with the DMA.

  dmai structure:
       typedef struct vidix_dma_s
       {
           void *src;               /* app -> driver: Virtual address of source */
           unsigned dest_offset;    /* app -> driver: Destination offset within of video memory */
           unsigned size;           /* app -> driver: Size of transaction */
       #define BM_DMA_NOSYNC      0
       #define BM_DMA_SYNC        1 /* wait previous dma transfer completion */
       #define BM_DMA_FIXED_BUFFS 2 /* app uses buffers witch are fixed in memory */
       #define BM_DMA_BLOCK       4 /* block until the transfer is complete */
           unsigned flags;          /* app -> driver */
           unsigned idx;            /* app -> driver: index of the src buffer */
           unsigned src_incr;       /* app -> driver: if src_incr & dest_incr are */
           unsigned dest_incr;      /*                different, else 0 */
           void *internal[VID_PLAY_MAXFRAMES];    /* for internal use by driver */
       }vidix_dma_t;

  Binding:
          pea.l   dmai
          move.w  #416,-(sp)
          trap    #14
          addq.l  #6,sp
          
  Return: Driver should return 0 else EINVAL, ERANGE, ENOMEM, E2BIG or 
          ENOSYS.

*************************************************************************
			vdxQueryDMAStatus    
*************************************************************************

  Opcode:
       XBIOS 417

  Syntax:
       int vdxQueryDMAStatus(void);

  Description:
          Function for get the status of the DMA after a vdxPlaybackCopyFrame().

  Binding:
          move.w  #417,-(sp)
          trap    #14
          addq.l  #2,sp
          
  Return: Driver should return 0 or 1 if busy, else ENOSYS.

*************************************************************************
